---
sort: "0001"
title: "iOS SDK 1.0"

---

# Jitsu iOS SDK

Jitsu iOS SDK allows you to send data to Jitsu from iOS applications.

## Installation
You can install with [Cocoapods](https://cocoapods.org), [Carthage](https://github.com/Carthage/Carthage), or [Swift Package Manager](https://swift.org/package-manager/).

### Cocoapods
Add the pod to your Podfile:
`pod 'Jitsu'`

And then run:
`pod install`

After installing the cocoa pod into your project, import Jitsu into your project.

### Carthage
Create a file named `Cartfile` in your projects folder.
Add Jitsu to your Cartfile: `github "jitsucom/jitsu-ios" "main"`.

And then run:
`carthage update --use-xcframeworks`

Open `Carthage/Build` directory, and drag Jitsu.framework to your application targets “General” tab under the “Linked Frameworks and Libraries” section.

If your app can't find Jitsu, go to your target's build settings, and add `$(SRCROOT)`  `recursive`  to your `Framework search path` .

Then import Jitsu into your project.


### Swift Package Manager
1. Go to File > Swift Packages > Add Package Dependency
2. Paste the project URL: https://github.com/jitsucom/jitsu-ios.git
3. Click on next and select the project target
4. Don't forget to set `DEAD_CODE_STRIPPING = NO` in your `Build Settings`(https://bugs.swift.org/plugins/servlet/mobile#issue/SR-11564)

After successfully retrieved the package and added it to your project, import Jitsu.

### Importing Jitsu

<CodeInTabs>
    <CodeTab title="Swift" lang="swift">{`
import Jitsu
    `}</CodeTab>
    <CodeTab title="Objective-C" lang="objectivec">{`
@import Jitsu;
    `}</CodeTab>
</CodeInTabs>


## Initialization
SDK is configured with  `JitsuOptions`.
You should provide your Client secret token and Tracking url.

| Parameter | Description |
| :--- | :--- |
| CLIENT_SECRET_KEY | Client secret key can be obtained from Jitsu UI Events API section or from [Configuration](https://jitsu.com/docs/configuration)  |
| TRACKING_URL | Full URL of `/api/v1/event` endpoint of your deployment, e.g.: `https://example.com/api/v1/event`. For cloud version of Jitsu pass `nil` value|

<CodeInTabs>
    <CodeTab title="Swift" lang="swift">{`
let options = JitsuOptions(apiKey: "CLIENT_SECRET_KEY", trackingHost: "TRACKING_URL")
Jitsu.setupClient(with: options)
`}</CodeTab>
    <CodeTab title="Objective-C" lang="objectivec">{`
JitsuOptions *options = [[JitsuOptions alloc] initWithApiKey:@"CLIENT_SECRET_KEY" trackingHost:@"TRACKING_URL" logLevel: JitsuLogLevelDebug];
[Jitsu setupClientWith: options];
`}</CodeTab>
</CodeInTabs>

## Sending events

### Sending events
There are two ways of sending events:

a) client can send an event as something conforming to `Event` protocol

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
let event = JitsuBasicEvent(name: "hi")
Jitsu.shared.trackEvent(event)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
JitsuBasicEvent * event = [[JitsuBasicEvent alloc] initWithName:@"hi" payload:@{}];
[Jitsu.shared trackEvent: event]; 
`}</CodeTab>
</CodeInTabs>


b) or pass it as a name of event and Dict of event params.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.shared.trackEvent(_ name: "user pressed like", params: ["to_user_id: "NEW_VALUE"])
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.shared trackEventWithName:@"Hi from Objective-C" payload: @{@"id": [NSUUID new]}];
`}</CodeTab>
</CodeInTabs>

### Identifying user
Information about the user is passed with events.

Use `Jitsu.userProperties` to manage user info.
UserProperties consist of an anonymous user id and custom identifiers that you can set to the user.

**anonymous user id**:
Jitsu automatically sets a UUID to any user that is stored between launches.
You can get it by `Jitsu.userProperties.anonymousUserId`.

**user identifier**:
You can set your own identifier to user.
You can access it  by `Jitsu.userProperties.userIdentifier`.
You can set new identifier with:

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.userProperties.updateUserIdentifier("NEW_ID", sendIdentificationEvent: true)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.userProperties updateUserIdentifier:@"new identifier" sendIdentificationEvent:YES];
`}</CodeTab>
</CodeInTabs>


**email**:
You can set email.
You can access it by `Jitsu.userProperties.email`.
You can update it with:

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.userProperties.updateEmail("new@new.com", sendIdentificationEvent: true)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.userProperties updateEmail: @"new@new.com" sendIdentificationEvent:TRUE];
`}</CodeTab>
</CodeInTabs>


**other identifiers**:
You can set additional user identifiers.
You can access it by `Jitsu.userProperties.otherIdentifiers`.
You can update it with:

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.userProperties.updateOtherIdentifier(forKey: "my_key", with: "new_value", sendIdentificationEvent: true)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.userProperties updateOtherIdentifierForKey:@"my_key" with:@"new_value" sendIdentificationEvent:YES];
`}</CodeTab>
</CodeInTabs>


**You can set multiple user properties**:

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.userProperties.identify(
	userIdentifier: "my_id",
	email: "foo@bar.com",
	otherIds: ["name": "Foo", "surname": "Johnson"],
	sendIdentificationEvent: true
)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.userProperties identifyWithUserIdentifier: @"my_id"
						email: @"foo@bar.com"
					   otherIds:@{ @"name": @"Foo", @"surname": @"Johnson" }
				sendIdentificationEvent: YES];
`}</CodeTab>
</CodeInTabs>

**You can reset all users properties.**
All the properties set before will be reset, and new `anonymous_id` will be generated.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.userProperties.resetUserProperties()
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.userProperties resetUserProperties];
`}</CodeTab>
</CodeInTabs>


### Context
You can set properties that will always be added to events of certain types.
You can add, change and remove context values.
You can either add properties to certain event types or do not specify event type - then it will be added to all the event types.
You can also set if you want context values persisted between launches. By default, context events are not persisted.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.context.addValues(
	["age": 32, "codes": "Swift"], 
	for: ["event sign up"],
	persist: true
)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.context addValues:@{@"language": @"Objective-C"} for: @[@"hi"] persist:NO];
[Jitsu.context addValues:@{@"general": @"value"} for: nil persist:NO];
`}</CodeTab>
</CodeInTabs>


You can remove context values by calling

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.context.removeValue(for key: "language", for eventTypes: nil)
Jitsu.context.removeValue(for key: "language", for eventTypes: ["hi"]])
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.shared.context removeValueFor:@"age" for: nil];
[Jitsu.context removeValueFor:@"language" for: @[@"hi"]];
`}</CodeTab>
</CodeInTabs>


You can clear context when needed. It will not clear automatically gathered values (only update them).

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.context.clear()
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.context clear];
`}</CodeTab>
</CodeInTabs>

SDK automatically gathers some context values.

#### Automatically gathered context values
* device info: model, screen size, OS version
* app version, app name, sdk version
* system language
* `voice_over: true` if the user has VoiceOver on.

### Send screen event
You can send an event from a screen in one line. This event will contain screen title and screen class as well as event data.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.shared.trackScreenEvent(screen: self, event: JitsuBasicEvent(name: "screen opened"))
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.shared trackScreenEventWithScreen:self name:@"screen opened" payload:@{}];
`}</CodeTab>
</CodeInTabs>

## Out-of-the-box Trackings
Jitsu can do some tracking for you.
You can set what to track when initializing SDK with `JitsuOptions`.
*  Main app lifecycle events: `shouldCaptureAppLifecycleEvents`
*  When the app was updated or installed
*  User opens a push notification: `shouldCapturePushEvents`
*  The app was opened from a deeplink. `shouldCaptureDeeplinks`. We pass the link in payload. *Note: this method will not work if your app uses SceneDelegate. If so, you will have to track opening from deeplink manually in `scene(_ scene: , willConnectTo session: , options connectionOptions: )`*

### Location
SDK can gather info about location. There are two modes which you can set in options.
SDK uses the permissions that your app has and would never ask the user for permission by itself.
* `trackPermissionChanges` - SDK tracks location permission changes. We add current location permission status to the context, and send events when it changes.
* `addLocationOnAppLaunch` - If user granted access to location, we gather a new location every time the app launches and add it to the context.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
options.locationTrackingOptions = [.addLocationOnAppLaunch, .trackPermissionChanges]
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[options setLocationTrackingOptions: @[@(LocationTrackingOptionsTrackPermissionChanges), @(LocationTrackingOptionsAddLocationOnAppLaunch)]];
`}</CodeTab>
</CodeInTabs>


Also there is a special event type method that allows to send location events easily:

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
let event = LocationEvent(location: location, name: "left bike", payload: [:])
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
LocationEvent *event = [[LocationEvent alloc] initWithName: @"hi" location: location payload: @{}];
`}</CodeTab>
</CodeInTabs>


## Privacy Settings
Jitsu SDK doesn't collect any persistent device identifiers.

You can allow your users to disable/enable data collection.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.shared.turnOff()
Jitsu.shared.turnOn()
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[Jitsu.shared turnOff];
[Jitsu.shared turnOn];
`}</CodeTab>
</CodeInTabs>


That will generate `Jitsu turned off` and `Jitsu turned on` events


## Logging
You can set log level when initializing SDK with JitsuOptions .

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
options.logLevel = .critical
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[options setLogLevel: JitsuLogLevelInfo];
`}</CodeTab>
</CodeInTabs>

where `JitsuLogLevel` has values `debug`, `info`, `warnings`, `errors`, `critical`, `none`


## UnitTestMode
1) You can set up your own mock of Jitsu by calling `Jitsu.setupMock:`.  If you pass `nil`, we will create our own empty mock
2) Jitsu automatically tracks if your app is in Unit Testing mode. If so, it disables sending data to the backend and saving it to the database.


## Advanced Settings
* Jitsu uses an internal queue to make calls fast and non-blocking.
* Jitsu doesn't send each event immediately. Instead, it sends events in batches. SDK sends a new batch either when it reaches eventsQueueSize, or every sendingBatchesPeriod. Also, Jitsu sents all unsent events when an application enters the background state. If the app gets closed or crashes, events are sent on the next launch. You can manually set the number of events in the queue and time period.

<CodeInTabs>
<CodeTab title="Swift" lang="swift">{`
Jitsu.shared.eventsQueueSize = 20
Jitsu.shared.sendingBatchesPeriod = TimeInterval(10)
`}</CodeTab>
<CodeTab title="Objective-C" lang="objectivec">{`
[[Jitsu shared] setEventsQueueSize: 20];
[[Jitsu shared] setSendingBatchesPeriod: 10];
`}</CodeTab>
</CodeInTabs>

Also, you can force SDK to send batch immediately by calling `sendBatch` method.